Scientific writing

Word processor programs

• The most popular writing programs are Microsoft Word (first released in 1983 as Multi-Tool Word) and the much newer Google Docs (2006) ¹.

• They are often referred to “What You See Is What You Get” (WYSIWYG) text processors.

• Common tasks in scientific writing can take more time than they should when working with WYSIWYG.

Markup languages: A different paradigm

• A markup language uses special codes to structure and format text.

• One of the first markup languages is TeX (released in 1978). LaTeX is the most popular TeX-based language.

• A popular (and newer) markup language is Markdown. Some Markdown extensions incorporate LaTeX features.

• Markdown is used extensively in GitHub (and GitLab); it is also popular for blogging.

Literate programming (LP)

• Sweave (Leisch 2002)

• Org-mode (Schulte et al. 2012)

• RMarkdown (Xie et al. 2018)

• Quarto

Why using LP?

• Content driven writing

• Consistency and automation

• Portability and longevity

• Version control

Quarto: Next-Gen R Markdown

• Quarto is a literate programming that superseded R Markdown.

• It is a standalone (sort of) piece of software instead of a package.

• Support for several languages: R, python, julia, javascript.

• It aims at making reproducible research and publications the norm rather than the exception.

What do I need to write Quarto documents?

Who is Quarto for and why should I use it?

• Everyone wishing to produce beautiful documents can benefir from this tool.

• You don’t need to be a hardcore programmer to use it, but you must not fear coding.

• The tool is specially appealing for professionals who write documents with many equations.

• Quarto makes creating reproducible documents seamless.

• A single tool that produces reports, books, presentations, and even websites.

Basic structure

---
title: "My Quarto Document"
format:
  html:
    code-fold: true
jupyter: python3
---

## My title

### My subtitle

Writing in _italic_, **bold**. A [hyperlink to quarto
website](https://quarto.org)

* list item 1

  * list sub-item

* list item 2

Equations

• Equations can be rendered inline and on their own line. See the example below.

The density of a normally distributed random variable $X$ with mean $\mu$ and
variance $\sigma^2$ is 
$$
f(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left \{ \frac{1}{2 \sigma^2} (x -
\mu)^2 \right \}
$$

Figures

![This is Cacau. Cacau in Portuguese means cocoa.](<adress-of-my-figure>)

Sub-Figures

::: {#fig-both layout-ncol=2}

![This is Cacau. Cacau in Portuguese means cocoa.](<adress-of-my-figure>)

![This is Kalu. She is not happy I'm using pictures of dogs.](<adress-of-my-figure>)

My Caption!
:::

Code execution

#| label: fig-peng
#| fig-cap: "A scatterplot."

library(ggplot2)
library(palmerpenguins)
library(dplyr)

data(package = "palmerpenguins")

ggplot(data = penguins,
       aes(x = flipper_length_mm,
           y = bill_length_mm,
           color = species)) +
  geom_point() +
  theme_bw() +
  labs(x = "Flipper length (mm)",
       y = "Bill length (mm)",
       color = "Species") +
  theme(legend.position = "top")

Code execution

Figure 2: A scatterplot.

Tables

• There are many options/configurations for tables available (see this link).

• One can simply generate tables from code.

#| label: tbl-peng
#| tbl-cap: "Penguins again."

penguins |>
  count(species) |>
  mutate(proportion = 100 * n / sum(n)) |>
  arrange(desc(n)) |>
  knitr::kable(digits = 1)

Cross-referencing

• In Quarto we can cross-reference Sections, Equations, Figures, and Tables – we will refer to these categories as “entities”.

• To enable this feature, each entity must have a label (unique identifier) and, for figures and tables, a caption. See Table 2.

Citations

• Quarto does not have a Zotero plugin (tutorials on how to use them together)

• Before Zotero, there was BIBTeX!

• BIBTeX is both a bibliographic database file format and a software for processing references (citations). References are listed in a .bib file (show how to obtain bib entries).

@article{matthews2019craft,
  title =        {Craft beautiful equations in {W}ord with {LaTeX}},
  author =       {Matthews, David and others},
  journal =      {Nature},
  volume =       570,
  number =       7760,
  pages =        {263--264},
  year =         2019,
  publisher =    {Nature}
}

One source many outputs

• I used the same code to generate a presentation, a pdf file, and an html report.

• I will show the source for these files and their respective outputs.

• I also used this example to showcase how Quarto’s cross-referencing works.

Overview

• Quarto can enhance your productivity and the reproducibility of your research material

• As any code-related resource, the learning curve may be steep

• Once you learn it, you can easily recycle and modify documents according to changes in your data

• It is trivial to change documents’ style.

• Although Quarto is open-source, its main developer (and maintainer) is a company (posit)

Resources

• Quarto website provides many resources.

• The gallery has examples categorized by their type (i.e., presentations, reports, etc)

• A curated list of resources and features is available at awesome-quarto on GitHub.

• I have a blog post on how to create your personal website using Quarto. The post also shows how to host it on GitHub Pages.

• Coding style guides